Event Types Reference

Complete catalog of all 50+ event types organized by category

This is a comprehensive reference of all events emitted by HPD-Agent. For practical usage patterns, see Consuming Events.

Quick Navigation

• Turn Lifecycle Events - When agent starts/finishes
• Content Events - Text streaming
• Reasoning Events - Extended thinking
• Tool Events - Function calls
• Bidirectional Events - Request/response patterns
• Client Tools Events - Browser-side tool execution
• Observability Events - Internal diagnostics (filter these!)
• Supporting Types - Enums and interfaces

---

Turn Lifecycle Events

** CRITICAL**: MessageTurnFinishedEvent is when the agent is DONE. Use this to stop loading spinners!

Event Type	C# Class	Description	Common Use
MESSAGE_TURN_STARTED	MessageTurnStartedEvent	User message processing begins	Start loading indicator
MESSAGE_TURN_FINISHED	MessageTurnFinishedEvent	Agent finished ← Use this!	Stop loading, enable input
MESSAGE_TURN_ERROR	MessageTurnErrorEvent	Unrecoverable error	Show error message
AGENT_TURN_STARTED	AgentTurnStartedEvent	Internal LLM call begins	Debug/logging only
AGENT_TURN_FINISHED	AgentTurnFinishedEvent	Internal LLM call ends	Debug/logging only
STATE_SNAPSHOT	StateSnapshotEvent	Current iteration state	Show iteration count

MessageTurnStartedEvent

public record MessageTurnStartedEvent(
    string MessageTurnId,        // Unique ID for this message turn
    string ConversationId,        // Conversation/thread ID
    string AgentName,             // Name of the agent
    DateTimeOffset Timestamp      // When processing started
) : AgentEvent;

MessageTurnFinishedEvent

public record MessageTurnFinishedEvent(
    string MessageTurnId,        // Matches MessageTurnStartedEvent
    string ConversationId,
    string AgentName,
    TimeSpan Duration,           // How long the turn took
    DateTimeOffset Timestamp
) : AgentEvent;

MessageTurnErrorEvent

public record MessageTurnErrorEvent(
    string Message,              // Error message to show user
    Exception? Exception = null  // Full exception details
) : AgentEvent, IErrorEvent;

---

Content Events

The agent's text response streaming:

Event Type	C# Class	Description	Common Use
TEXT_MESSAGE_START	TextMessageStartEvent	Assistant message begins	Show message boundary
TEXT_DELTA	TextDeltaEvent	Streaming text chunk	Append to UI
TEXT_MESSAGE_END	TextMessageEndEvent	Assistant message complete	Mark message complete

TextDeltaEvent

public record TextDeltaEvent(
    string Text,      // The text chunk to display
    string MessageId  // Message identifier
) : AgentEvent;

Example:

case TextDeltaEvent delta:
    // Accumulate and display
    messageBuilder.Append(delta.Text);
    Console.Write(delta.Text);
    break;

---

Reasoning Events

Extended thinking (for reasoning-capable models like Claude, o1, DeepSeek-R1):

Event Type	C# Class	Description	Common Use
REASONING_MESSAGE_START	ReasoningMessageStartEvent	Reasoning begins	Show "Thinking..." indicator
REASONING_DELTA	ReasoningDeltaEvent	Streaming reasoning content	Display internal thoughts
REASONING_MESSAGE_END	ReasoningMessageEndEvent	Reasoning complete	Hide thinking indicator

ReasoningDeltaEvent

public record ReasoningDeltaEvent(
    string Text,      // Reasoning content chunk
    string MessageId
) : AgentEvent;

Example:

case ReasoningDeltaEvent reasoning:
    Console.Write($"[Thinking: {reasoning.Text}]");
    break;

---

Tool Events

When the agent calls functions:

Event Type	C# Class	Description	Common Use
TOOL_CALL_START	ToolCallStartEvent	Tool invocation begins	Show "Calling tool..."
TOOL_CALL_ARGS	ToolCallArgsEvent	Tool arguments available	Display arguments
TOOL_CALL_END	ToolCallEndEvent	Tool call complete	Mark tool finished
TOOL_CALL_RESULT	ToolCallResultEvent	Tool execution result	Show result/error

ToolCallStartEvent

public record ToolCallStartEvent(
    string CallId,     // Unique call identifier
    string Name,       // Tool/function name
    string MessageId
) : AgentEvent;

ToolCallResultEvent

public record ToolCallResultEvent(
    string CallId,
    string Result      // JSON result or error message
) : AgentEvent;

Example:

case ToolCallStartEvent toolStart:
    Console.WriteLine($"\n[Calling: {toolStart.Name}]");
    break;

case ToolCallResultEvent toolResult:
    Console.WriteLine($"[Result: {toolResult.Result}]");
    break;

---

Bidirectional Events

** CRITICAL**: These events require calling agent.SendMiddlewareResponse() or the agent will hang!

Permission Events

Request/response pattern for user approval:

Request Event	Response Event	Description
PermissionRequestEvent	PermissionResponseEvent	Ask user to approve tool execution
ContinuationRequestEvent	ContinuationResponseEvent	Ask to continue beyond max iterations

PermissionRequestEvent

public record PermissionRequestEvent(
    string PermissionId,                   // Unique ID for this request
    string SourceName,                      // Middleware that requested
    string FunctionName,                    // Tool being called
    string? Description,                    // Human-readable description
    string CallId,                          // Tool call ID
    IDictionary<string, object?>? Arguments // Tool arguments
) : AgentEvent, IPermissionEvent;

PermissionResponseEvent

public record PermissionResponseEvent(
    string PermissionId,                    // Matches request
    string SourceName,
    bool Approved,                          // User's decision
    string? Reason = null,                  // Optional reason
    PermissionChoice Choice = PermissionChoice.Ask
) : AgentEvent, IPermissionEvent;

Example:

case PermissionRequestEvent permission:
    var approved = await PromptUserAsync($"Allow {permission.FunctionName}?");

    // MUST send response or agent hangs!
    agent.SendMiddlewareResponse(permission.PermissionId,
        new PermissionResponseEvent
        {
            PermissionId = permission.PermissionId,
            SourceName = permission.SourceName,
            Approved = approved
        });
    break;

Clarification Events

Request additional information from the user:

Request Event	Response Event	Description
ClarificationRequestEvent	ClarificationResponseEvent	Ask user for more information

ClarificationRequestEvent

public record ClarificationRequestEvent(
    string RequestId,
    string SourceName,
    string Question,           // Question to ask user
    string? AgentName = null,  // Name of the agent asking
    string[]? Options = null   // Optional list of choices to present
) : AgentEvent, IClarificationEvent;

ClarificationResponseEvent

public record ClarificationResponseEvent(
    string RequestId,          // Matches request
    string SourceName,
    string Question,           // The original question being answered
    string Answer              // User's answer
) : AgentEvent, IClarificationEvent;

Notification Events

One-way notifications (no response needed):

Event Type	C# Class	Description
PERMISSION_APPROVED	PermissionApprovedEvent	Emitted after permission approved
PERMISSION_DENIED	PermissionDeniedEvent	Emitted after permission denied

---

Client Tools Events

For tools that execute in the browser/client (file pickers, geolocation, etc.):

Event Type	Description
ClientToolInvokeRequestEvent	Agent requests client-side tool execution
ClientToolInvokeResponseEvent	Client returns tool result
ClientToolkitsRegisteredEvent	Client registered its tool groups
CollapsedToolsVisibleEvent	Collapsed tools are now visible
ContainerExpandedEvent	Container was expanded

---

Streaming Control Events

InterruptionRequestEvent

Emitted to request interruption of active streams or operations. Used for user-initiated stops and system-level cancellations.

public record InterruptionRequestEvent(
    string? StreamId,          // Stream to interrupt (null = all streams)
    string Reason,             // Human-readable reason
    InterruptionSource Source  // Who initiated: User, System, Parent, Middleware
) : AgentEvent;

---

Structured Output Events

Events emitted during RunStructuredAsync<T>():

Event Type	C# Class	Description
STRUCTURED_RESULT	StructuredResultEvent<T>	Parsed result (may be partial)

StructuredResultEvent<T>

public sealed record StructuredResultEvent<T>(
    T Value,         // Parsed value (partial or complete)
    bool IsPartial,  // True if streaming still in progress
    string RawJson   // Raw JSON that was parsed
) : AgentEvent where T : class;

Example:

case StructuredResultEvent<WeatherReport> result:
    if (result.IsPartial)
        UpdatePreviewUI(result.Value);  // Show partial data as it streams
    else
        ShowFinalResult(result.Value);  // Final complete object
    break;

---

Observability Events

** ALWAYS FILTER THESE OUT** in user-facing code!

These implement IObservabilityEvent and are for internal diagnostics:

// FIRST LINE of your event handler:
if (evt is IObservabilityEvent) continue;

Event Type	C# Class	Description
MIDDLEWARE_PROGRESS	MiddlewareProgressEvent	Middleware processing update
MIDDLEWARE_ERROR	MiddlewareErrorEvent	Middleware failure
MIDDLEWARE_PIPELINE_START	MiddlewarePipelineStartEvent	Pipeline processing begins
MIDDLEWARE_PIPELINE_END	MiddlewarePipelineEndEvent	Pipeline processing complete
PERMISSION_CHECK	PermissionCheckEvent	Permission check timing
ITERATION_START	IterationStartEvent	Agent iteration begins
CIRCUIT_BREAKER_TRIGGERED	CircuitBreakerTriggeredEvent	Safety limit reached
HISTORY_REDUCTION_CACHE	HistoryReductionCacheEvent	History reduction metrics
CHECKPOINT	CheckpointEvent	State checkpoint saved
BACKGROUND_OPERATION_STARTED	BackgroundOperationStartedEvent	Async operation started
BACKGROUND_OPERATION_STATUS	BackgroundOperationStatusEvent	Async operation status
INTERNAL_PARALLEL_TOOL_EXECUTION	InternalParallelToolExecutionEvent	Parallel tool execution
INTERNAL_RETRY	InternalRetryEvent	Internal retry attempt
MODEL_CALL_RETRY	ModelCallRetryEvent	LLM streaming retry — clear partial UI text when received
FUNCTION_RETRY	FunctionRetryEvent	Function retry attempt
DELTA_SENDING_ACTIVATED	DeltaSendingActivatedEvent	Delta sending enabled
PLAN_MODE_ACTIVATED	PlanModeActivatedEvent	Plan mode activated
NESTED_AGENT_INVOKED	NestedAgentInvokedEvent	SubAgent spawned
DOCUMENT_PROCESSED	DocumentProcessedEvent	Document processing metrics
INTERNAL_MESSAGE_PREPARED	InternalMessagePreparedEvent	Message prepared
BIDIRECTIONAL_EVENT_PROCESSED	BidirectionalEventProcessedEvent	Bidirectional event handled
AGENT_DECISION	AgentDecisionEvent	Agent decision points
AGENT_COMPLETION	AgentCompletionEvent	Agent completion details
ITERATION_MESSAGES	IterationMessagesEvent	Messages for iteration
SCHEMA_CHANGED	SchemaChangedEvent	Schema changed
COLLAPSING_STATE	CollapsingStateEvent	Collapsing state update
EVENT_DROPPED	EventDroppedEvent	Events dropped (interruption)

ModelCallRetryEvent (Notable)

Although tagged as IObservabilityEvent, this event has a critical UI implication: clear any partial response text when received — a fresh response stream is about to begin.

public record ModelCallRetryEvent(
    int Attempt,          // Current retry number (1-based)
    int MaxRetries,       // Maximum retries configured
    TimeSpan Delay,       // Wait time before retry
    Exception Exception,
    string ExceptionType,
    string ErrorMessage
) : AgentEvent, IObservabilityEvent, IErrorEvent;

Example:

// Enable observability events to receive this
case ModelCallRetryEvent retry:
    responseBuffer.Clear();  // Clear partial text — fresh content coming
    Console.WriteLine($"Retrying (attempt {retry.Attempt}/{retry.MaxRetries})...");
    break;

---

Supporting Types

Enums

EventPriority

public enum EventPriority
{
    Immediate = 0,  // User cancellation, emergency stops
    Control = 1,    // System control signals
    Normal = 2,     // Standard data flow (DEFAULT)
    Background = 3  // Metrics, telemetry
}

EventDirection

public enum EventDirection
{
    Downstream,  // Normal: input → processing → output
    Upstream     // Control: cancellation signals flowing back
}

InterruptionSource

public enum InterruptionSource
{
    User,       // User clicked stop, pressed Ctrl+C
    System,     // Timeout, circuit breaker
    Parent,     // Parent agent aborting child
    Middleware  // Permission denied, validation failed
}

PermissionChoice

public enum PermissionChoice
{
    Ask,        // Ask user each time
    Allow,      // Always allow
    Deny        // Always deny
}

Marker Interfaces

IBidirectionalEvent

public interface IBidirectionalEvent
{
    string SourceName { get; }
}

Events that support request/response patterns.

IPermissionEvent

public interface IPermissionEvent : IBidirectionalEvent
{
    string PermissionId { get; }
}

Permission-related events.

IClarificationEvent

public interface IClarificationEvent : IBidirectionalEvent
{
    string RequestId { get; }
    string Question { get; }
}

Clarification-related events.

IObservabilityEvent

public interface IObservabilityEvent { }

Marker for internal diagnostic events that should be filtered out.

IErrorEvent

public interface IErrorEvent
{
    string ErrorMessage { get; }
}

Events representing errors.

AgentEvent Base Class

All events inherit from AgentEvent:

public abstract record AgentEvent
{
    public AgentExecutionContext? ExecutionContext { get; init; }
    public EventPriority Priority { get; init; } = EventPriority.Normal;
    public long SequenceNumber { get; internal set; }
    public EventDirection Direction { get; init; } = EventDirection.Downstream;
    public string? StreamId { get; init; }
    public bool CanInterrupt { get; init; } = true;
}

AgentExecutionContext

For nested agent scenarios (see SubAgent Events):

public record AgentExecutionContext
{
    public required string AgentName { get; init; }
    public required string AgentId { get; init; }
    public string? ParentAgentId { get; init; }
    public IReadOnlyList<string> AgentChain { get; init; }
    public int Depth { get; init; }
    public bool IsSubAgent => Depth > 0;
}

---

See Also

• Events Overview - Event lifecycle and concepts
• Consuming Events - Practical event handling patterns
• SubAgent Events - Nested agent filtering
• Bidirectional Events - Request/response deep dive
• Custom Events - Creating your own events